Updated section on semantic interoperability (issues #1217 and #1210) #1420
Conversation
iherman
requested review from
msporny,
selfissued and
decentralgabe
as code owners
iherman
changed the title
The change could be to use SHOULD/RECOMMENDED everywhere. However. "Testability" in the W3C CR setting is a very general concept; the goal is to prove that a feature is implementable by two, independent implementations (to ensure interoperability). From a CR point of view, this does not mean that each MUST should have a running test program. (The usual counterexample is the "testing" of a vocabulary, which means that the terms are in use by at least two different implementations.) Taking this view, the few MUST statements in this section are easily testable: it requires at least two VC applications that define their own application specific terms, and that abide to these requirements. Isn't that feasible? (Personally, I would prefer, from the spec's point of view, to keep those MUST-s.) |
All adopted. |
index.html
Outdated
| Human-readable documentation MUST be published, describing the semantics of and | ||
| the constraints on the use of each term. |
There was a problem hiding this comment.
This section is turning into a "Requirements for Vocabulary Document Authors", which I thought we were going to avoid writing as of last week. IOW, this PR feels like it's trying to also address issue #1410
That said, this isn't a bad list (although, some of it feels a bit heavy handed)...
index.html
Outdated
| Furthermore, a machine-readable description (that is, a | ||
| <a data-cite="JSON-LD11#dfn-context">JSON-LD Context document</a>) MUST be published at the URL specified | ||
| in the `@context` [=property=] for the vocabulary. |
There was a problem hiding this comment.
We don't need to say this. The document will be non-conformant if this is not done.
There was a problem hiding this comment.
I am not sure I understand this remark. Yes, the document will be non conformant, because the JSON-LD processor will fail if the @context value does not dereference. But if the user does not publish a context document nor does he/she put a @context property for the vocabulary, the document will pass, thanks to the @vocab in the core context...
index.html
Outdated
| This context MUST map each term to its corresponding URL, possibly accompanied by further | ||
| constraints like the type of the property value. A human-readable document describing the expected order of values for |
There was a problem hiding this comment.
Does this statement go against the usage of @vocab? It's not technically true, is it, that a context MUST map each term to its corresponding URL (because if it doesn't, the issuer-specific vocabulary statement takes over).
There was a problem hiding this comment.
Hm. What I wanted to say is that the context defined for the vocabulary MUST map each term in this vocabulary to the corresponding URL (plus define constraints). This pre-empts the effect of @vocab. I am not sure what the problem is...
There was a problem hiding this comment.
A few questions and changes requested. Overall, we should decide if we're also addressing issue #1410 with this PR (as we're dangerously close to doing so, IMHO).
Some of the normative statements feel a bit heavy-handed (and untestable -- or should we test them?).
See my comments in #1420 (comment). If we do have two "properly defined" vocabularies around as part of the implementations, then, CR-wise, we are o.k. No reason for explicit "tests" imho. |
We are not "dangerously close": we are covering it. A 'type' is part of a vocabulary, whether new properties are defined or not. I am not sure whether we need to make it explicit in this text, and how. Maybe by defining (in the terms' section) what we mean by 'vocabulary': something that may be as simple as the definition of new types, and as complex as defining whole new properties. |
|
The issue was discussed in a meeting on 2024-02-07
View the transcript3.4. Updated section on semantic interoperability (issues #1217 and #1210) (pr vc-data-model#1420)See github pull request vc-data-model#1420. Manu Sporny: A number of PRs for VCDM. Huge thanks to ivan for raising a number of them. One we should talk about today (1420). Ivan raised. Ivan Herman: AFAIK, a new draft with normative changes are OK provided that at some point in time we publish a snapshot with these changes. I don't think there is any problem with these few normative changes here. We know we will republish a snapshot sometime in May. I think we are fine.
Manu Sporny: That is my read as well. I've started tracking this with a normative label so we know we have done a second CR triggering thing and that we can summarize these changes. If you raise a PR, please try to classify as Editorial or Normative. Ivan Herman: If a change is normative in a serious way, then the editor of the PR should add an item to the list of changes at the end of the document or we will forget them.
Brent Zundel: this is something reviews should remind when examining PRs. Manu Sporny: A number of editorial changes are out there and folks should pay attention. |
Co-authored-by: Ted Thibodeau Jr <[email protected]>
Co-authored-by: David I. Lehn <[email protected]>
Co-authored-by: Manu Sporny <[email protected]>
Co-authored-by: Manu Sporny <[email protected]>
msporny
force-pushed
the
iherman-ld-principles-and-vocab
branch
from
3f5c4d6 to
83dfad7
Compare
|
Normative, multiple reviews, changes requested and made, no objections, merging. |
|
BTW, I think this PR just created a new conformance class for vocabulary documents in the spec... If you agree, @iherman, we might want to add that conformance class and point it to the semantic interop section. I'll also note that I still think that this is a partial solution for #1410 because we don't add the text that I believe @jyasskin was looking for. |
This PR is an attempt to jointly cover issues #1217 and #1210, by a thorough re-write of §5.3.1 on Semantic Interoperability.
This is a normative section, ie, special attention should be given to the usage of the MUST, SHOULD, etc, keywords. My general approach was to reduce the MUST to the strict minimum, but reviewers might differ.
Preview | Diff